package cn.song.freight.service;

import cn.song.freight.domain.dto.PricingAreaMappingBatchDTO;
import cn.song.freight.domain.dto.PricingAreaMappingQueryDTO;
import cn.song.freight.domain.entity.PricingAreaMappingDO;
import com.baomidou.mybatisplus.extension.service.IService;

import java.util.List;
/**
 * 定价区域映射服务接口（V3版本核心组件）
 * <pre>
 * 该服务是V3版本架构的核心组件之一，负责管理定价配置与区域之间的多对多映射关系。
 * 通过解耦定价配置和区域管理，实现了更灵活、可扩展的运费策略配置架构。
 *
 * 核心功能特性：
 * 1. 多对多映射管理：一个定价配置可以应用于多个区域，一个区域可以关联多个定价配置
 * 2. 批量操作支持：提供高效的批量新增、删除操作，减少数据库交互次数
 * 3. 智能去重机制：自动检测并避免重复的映射关系，确保数据一致性
 * 4. 事务安全保证：所有写操作都具备事务回滚能力，确保数据完整性
 * 5. 全面的查询支持：支持正向、反向查询，满足各种业务场景需求
 * 6. 级联删除管理：提供安全的级联删除功能，维护数据关系的完整性
 *
 * 架构设计理念：
 * - 单一职责原则：专注于映射关系的管理，不涉及具体的定价逻辑
 * - 高内聚低耦合：与定价配置和区域管理模块保持松耦合关系
 * - 性能优化导向：通过批量操作和优化的SQL查询提高系统性能
 * - 扩展性友好：支持未来业务规则的扩展和变更
 *
 * 业务应用场景：
 * - 运费策略配置：为不同区域配置不同的运费定价策略
 * - 区域定价管理：管理复杂的区域定价规则和映射关系
 * - 批量区域操作：支持大批量区域的策略调整和配置变更
 * - 定价策略迁移：支持定价配置在不同区域间的灵活调整
 *
 * 性能优化特性：
 * - 批量数据处理：减少数据库往返次数，提高操作效率
 * - 智能缓存机制：为高频查询提供缓存支持（预留扩展接口）
 * - 优化的查询策略：使用高效的SQL查询和索引设计
 * - 事务优化：合理的事务边界设计，平衡性能和一致性
 *
 * @author SongRenShuo
 * @version 3.0.0
 * @since 2025-08-25
 */
public interface PricingAreaMappingService extends IService<PricingAreaMappingDO> {
    /**
     * 根据查询条件查询定价区域映射列表（支持多维度查询）
     * <pre>
     * 该方法提供灵活的查询能力，支持按定价ID、区域ID、操作人等多个维度进行查询。
     * 支持空参数查询和组合条件查询，结果按创建时间降序排列。
     *
     * 查询策略优化：
     * - 懒加载：仅在提供查询条件时才构建相应的WHERE条件
     * - 索引友好：查询条件按照数据库索引设计优化
     * - 精确匹配与模糊匹配结合：数值类型精确匹配，文本类型支持模糊查询
     *
     * @param queryDTO 查询条件DTO，支持以下参数：
     *                 - pricingId: 定价配置ID（精确匹配）
     *                 - areaId: 区域ID（精确匹配）
     *                 - operator: 操作人（模糊匹配，支持部分匹配）
     *                 - strategyId: 策略ID（预留字段，需要在上层处理关联查询）
     * @return List<PricingAreaMappingDO> 定价区域映射列表，按创建时间降序排列
     * @since 3.0.0
     */
    List<PricingAreaMappingDO> list(PricingAreaMappingQueryDTO queryDTO);

    /**
     * 批量新增定价区域映射关系（高效批量处理，智能去重）
     * <pre>
     * 该方法提供高效的批量新增能力，通过优化的数据库查询和批量插入减少系统开销。
     * 内置智能去重机制，自动过滤已存在的映射关系，确保数据一致性和完整性。
     *
     * 性能优化特性：
     * - 批量检查：一次查询获取所有已存在的映射，避免在循环中逐个查询
     * - 批量插入：使用数据库的批量插入功能，显著提高写入效率
     * - 内存优化：在内存中完成数据预处理，减少数据库交互
     * - 事务管理：保证批量操作的原子性，全部成功或全部回滚
     *
     * @param batchDTO 批量操作DTO，包含：
     *                 - pricingId: 定价配置ID（必需）
     *                 - areaIds: 区域ID列表（必需，非空）
     *                 - operator: 操作人（用于审计和权限控制）
     * @return boolean 操作是否成功：true=成功，false=失败或参数无效
     * @throws RuntimeException 当数据库操作异常时抛出
     * @since 3.0.0
     */
    boolean batchAdd(PricingAreaMappingBatchDTO batchDTO);

    /**
     * 批量删除定价区域映射关系（高效批量删除，安全可靠）
     * <pre>
     * 该方法提供高效的批量删除能力，通过一次SQL操作完成多个映射关系的删除。
     * 使用事务保证数据一致性，支持部分删除场景（即使某些映射不存在也不会影响整体操作）。
     *
     * 优势特性：
     * - 原子性保证：使用数据库事务确保所有删除操作的原子性
     * - 高效执行：一次SQL查询完成所有删除，避免多次数据库交互
     * - 容错设计：即使部分映射不存在也不会影响整体操作结果
     * - 安全验证：对输入参数进行全面验证，避免非法操作
     *
     * @param batchDTO 批量操作DTO，包含：
     *                 - pricingId: 定价配置ID（必需，用于精确定位）
     *                 - areaIds: 要删除的区域ID列表（必需，非空）
     * @return boolean 操作是否成功：true=成功，false=失败或参数无效
     * @throws RuntimeException 当数据库操作异常时抛出
     * @since 3.0.0
     */
    boolean batchDelete(PricingAreaMappingBatchDTO batchDTO);

    /**
     * 根据定价配置ID查询关联的区域ID列表
     * @param pricingId 定价配置ID
     * @return 区域ID列表
     */
    List<Long> getAreaIdsByPricingId(Long pricingId);

    /**
     * 根据多个定价配置ID批量查询所有相关的映射关系（性能优化方法）
     * <pre>
     * 该方法提供高效的批量查询能力，用于一次性获取多个定价配置的所有映射关系。
     * 相比逐个查询，该方法可以显著减少数据库交互次数，提升系统性能。
     * 
     * 性能优势：
     * - 查询效率：使用IN查询代替多次单独查询，减少数据库往返
     * - 内存优化：一次性获取所有数据，减少多次结果集处理
     * - 网络优化：减少网络传输次数，降低网络延迟影响
     * - 数据库优化：利用数据库查询优化器，提高查询执行效率
     * 
     * 适用场景：
     * - 批量数据处理：需要获取多个定价配置的映射关系
     * - 报表统计：统计分析多个定价配置的区域覆盖情况
     * - 数据导出：批量导出定价配置的映射数据
     * - 前端展示：为前端表格提供批量数据支持
     * 
     * @param pricingIds 定价配置ID列表（非空，支持大批量查询）
     * @return List<PricingAreaMappingDO> 所有相关的映射关系列表，按创建时间降序排列
     * @since 3.0.0
     */
    List<PricingAreaMappingDO> listByPricingIds(List<Long> pricingIds);

    /**
     * 根据区域ID查询关联的定价配置ID列表
     * @param areaId 区域ID
     * @return 定价配置ID列表
     */
    List<Long> getPricingIdsByAreaId(Long areaId);

    /**
     * 根据定价配置ID删除所有映射
     * @param pricingId 定价配置ID
     * @return 是否成功
     */
    boolean deleteByPricingId(Long pricingId);

    /**
     * 根据区域ID删除所有映射
     * @param areaId 区域ID
     * @return 是否成功
     */
    boolean deleteByAreaId(Long areaId);

    /**
     * 为定价配置重新设置关联的区域
     * @param pricingId 定价配置ID
     * @param areaIds 新的区域ID列表
     * @param operator 操作人
     * @return 是否成功
     */
    boolean resetAreaMapping(Long pricingId, List<Long> areaIds, String operator);

    /**
     * 检查定价配置和区域是否已经关联
     * @param pricingId 定价配置ID
     * @param areaId 区域ID
     * @return 是否已关联
     */
    boolean isAlreadyMapped(Long pricingId, Long areaId);
}
